As we discussed on the meeting, I don't think introducing this kind of new API that we would need to continuously maitain would add much better approach of what is public and what is not. We should have a clearly defined rules, but users will not check this and we would need to remember to take care of keeping all annotations in check.

I'm also not fully convinced TBH either, will come back to this a bit later. Also we can discuss more in community calls.

PR needs rebase.

@SamBarker @robobario @afalhambra-hivemq @gyfora @jiangzho @dongjoon-hyun

If you could give us feedback on this topic would be really helpful (see also related/linked issue), pls let us know if you see value in this (or not :) ).

thank you!!

Thank you for pinging me, @csviri . The idea looks reasonable. Just two questions.

thank you for reply!!

1. Are you going to mark every class and API into those three categories?

For practical reasons I originally planned just to make public API classes with @Public annotation; all other classes would be considered internal. But if a method what we for some reason we are not able to make non public, we will mark @Internal. But it is up to discussion, if that would bring more clarity, we marks all classes with one of those categories.

2. What happens for the existing downstream users who use some APIs which becomes Internal or Experimental or unmarked by this PR?

The @Experimental we already use, those members are subject of possible API change, there are not new changes regarding that.

If we marks an API @Public we would just guarantee that those won't change in a non backwards compatible way, so basically will change only in a major release. But this is purely serves as documentation, nothing will be enforced. For internal classes/methods we will not have that guarantee.

However, note that even this is sometimes hard to follow, and there might be no way around to change it in some exceptional cases. Considering for example change like we did between 4.2 -> 4.3, with condition API:
https://javaoperatorsdk.io/docs/migration/v4-3-migration/#condition-api-change

Where there was had good to have Conditions work on top of Dependent resources, not just secondary resource.
Shall we do it only in a major release in this case? According to semver yes. But we decided - since the conversion path is trivial - to not do that. So maybe in future, we might use more extensively @Experimental on new features, so we allow such changes. It is again up to discussion.

But, since we might do such minor changes anyways, it might be reasonable to define @Public in a way that those are classes users should use directly (not the others), and we follow semver as best effort (se exceptionally actually we might break semver).

So those are the dilemmas I see with this.